Modules¶
In previous chapter, we saw the *Zen* of Python . We also noticed
that this resides in this
module. In this chapter, we discuss about
modules. We also study how to create modules.
What is a module?¶
According to official documentation, a module is a file containing
Python definitions and statements. The file name is the module name with
the suffix .py
appended.
An Example¶
In a directory, create a file called fibo.py
and paste the following
code in it.
fibo.py
# Fibonacci numbers module
def fib(n): # write Fibonacci series up to n
a, b = 0, 1
while b < n:
print(b, end=' ')
a, b = b, a+b
print()
def fib2(n): # return Fibonacci series up to n
result = []
a, b = 0, 1
while b < n:
result.append(b)
a, b = b, a+b
return result
Now open ipython
(ipython3
) in the same directory and execute
the following statements:
>>> import fibo
This does not enter the names of the functions defined in fibo directly in the current symbol table; it only enters the module name fibo there. Using the module name you can access the functions:
>>> fibo.fib(1000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
>>> fibo.fib2(100)
[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
More ways to import
methods from
a module¶
There is a variant of the import
statement that imports names from a
module directly into the importing module’s symbol table. For example:
>>> from fibo import fib, fib2
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377
This does not introduce the module name from which the imports are taken
in the local symbol table (so in the example, fibo
is not defined).
There is even a variant to import all names that a module defines:
>>> from fibo import *
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377
This imports all names except those beginning with an underscore (_). In most cases Python programmers do not use this facility since it introduces an unknown set of names into the interpreter, possibly hiding some things you have already defined.
Executing modules as scripts¶
When you run a Python module with:
python fibo.py <arguments>
the code in the module will be executed, just as if you imported it, but
with the __name__
set to "__main__"
. That means that by adding
this code at the end of your module:
if __name__ == "__main__":
import sys
fib(int(sys.argv[1]))
you can make the file usable as a script as well as an importable module, because the code that parses the command line only runs if the module is executed as the “main” file:
python fibo.py 50
1 1 2 3 5 8 13 21 34
If the module is imported, the code is not run:
>>> import fibo
>>>
This is often used either to provide a convenient user interface to a module, or for testing purposes (running the module as a script executes a test suite).
The Module Search Path¶
When a module named spam
is imported, the interpreter first searches
for a built-in module with that name. If not found, it then searches for
a file named spam.py
in a list of directories given by the variable
sys.path
. sys.path
is initialized from these locations:
- The directory containing the input script (or the current directory when no file is specified).
PYTHONPATH
(a list of directory names, with the same syntax as the shell variablePATH
).- The installation-dependent default.
Packages¶
Packages are a way of structuring Python’s module namespace by using
“dotted module names”. For example, the module name A.B
designates a
submodule named B
in a package named A
. Just like the use of
modules saves the authors of different modules from having to worry
about each other’s global variable names, the use of dotted module names
saves the authors of multi-module packages like NumPy or the Python
Imaging Library from having to worry about each other’s module names.
Suppose you want to design a collection of modules (a “package”) for the
uniform handling of sound files and sound data. There are many different
sound file formats (usually recognized by their extension, for example:
.wav
, .aiff
, .au
), so you may need to create and maintain a
growing collection of modules for the conversion between the various
file formats. There are also many different operations you might want to
perform on sound data (such as mixing, adding echo, applying an
equalizer function, creating an artificial stereo effect), so in
addition you will be writing a never-ending stream of modules to perform
these operations. Here’s a possible structure for your package
(expressed in terms of a hierarchical filesystem):
sound/ Top-level package
__init__.py Initialize the sound package
formats/ Subpackage for file format conversions
__init__.py
wavread.py
wavwrite.py
aiffread.py
aiffwrite.py
auread.py
auwrite.py
...
effects/ Subpackage for sound effects
__init__.py
echo.py
surround.py
reverse.py
...
filters/ Subpackage for filters
__init__.py
equalizer.py
vocoder.py
karaoke.py
...
When importing the package, Python searches through the directories on sys.path looking for the package subdirectory.
The __init__.py
files are required to make Python treat the
directories as containing packages; this is done to prevent directories
with a common name, such as string, from unintentionally hiding valid
modules that occur later on the module search path. In the simplest
case, __init__.py
can just be an empty file, but it can also execute
initialization code for the package or set the __all__
variable,
described later.
Users of the package can import individual modules from the package, for example:
import sound.effects.echo
This loads the submodule sound.effects.echo
. It must be referenced
with its full name.
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
An alternative way of importing the submodule is:
from sound.effects import echo
This also loads the submodule echo
, and makes it available without
its package prefix, so it can be used as follows:
echo.echofilter(input, output, delay=0.7, atten=4)
Yet another variation is to import the desired function or variable directly:
from sound.effects.echo import echofilter
Again, this loads the submodule echo
, but this makes its function
echofilter()
directly available:
echofilter(input, output, delay=0.7, atten=4)
Note that when using from package import item
, the item
can be
either a submodule (or subpackage) of the package, or some other name
defined in the package, like a function, class or variable. The import
statement first tests whether the item is defined in the package; if
not, it assumes it is a module and attempts to load it. If it fails to
find it, an ImportError
exception is raised.
Contrarily, when using syntax like import item.subitem.subsubitem
,
each item except for the last must be a package; the last item can be a
module or a package but can’t be a class or function or variable defined
in the previous item.
Reference¶
This chapter is copied from Official Python Documentation